﻿using System;
using System.Collections.Generic;

namespace K3Cloud.WebApi.Core.IoC.Cache
{
    /// <summary>
    /// ICacheService 定义缓存服务接口，提供缓存的增删改查等基本操作。
    /// 支持泛型、过期时间控制等功能。
    /// </summary>
    public interface ICacheService
    {
        /// <summary>
        /// 创建缓存（永久缓存）。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="key">缓存键</param>
        /// <param name="value">缓存值</param>
        void Add<V>(string key, V value);

        /// <summary>
        /// 创建缓存（指定过期时间）。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="key">缓存键</param>
        /// <param name="value">缓存值</param>
        /// <param name="cacheDurationInSeconds">缓存时长（秒）</param>
        void Add<V>(string key, V value, int cacheDurationInSeconds);

        /// <summary>
        /// 检查缓存是否存在。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="key">缓存键</param>
        /// <returns>是否存在</returns>
        bool ContainsKey<V>(string key);

        /// <summary>
        /// 获取缓存值。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="key">缓存键</param>
        /// <returns>缓存值</returns>
        V? Get<V>(string key);

        /// <summary>
        /// 获取所有缓存主键。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <returns>缓存键集合</returns>
        IEnumerable<string> GetAllKey<V>();

        /// <summary>
        /// 移除指定缓存。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="key">缓存键</param>
        void Remove<V>(string key);

        /// <summary>
        /// 获取或创建缓存。
        /// 若缓存不存在，则调用创建函数并缓存结果。
        /// </summary>
        /// <typeparam name="V">缓存值类型</typeparam>
        /// <param name="cacheKey">缓存键</param>
        /// <param name="create">创建函数</param>
        /// <param name="cacheDurationInSeconds">缓存时长（秒）</param>
        /// <returns>缓存值</returns>
        V? GetOrCreate<V>(string cacheKey, Func<V> create, int cacheDurationInSeconds = int.MaxValue);

        /// <summary>
        /// 移除所有缓存。
        /// </summary>
        void RemoveAll();
    }
}